The PASI core technical documentation is primarily generated from comments that are stored in the PASI core's source code. These comments are extracted using a tool called Sandcastle (https://www.codeplex.com/Sandcastle) which produces two formats of documentation:
- A single .CHM (Microsoft compiled help format) file called PASI-API.chm
- An html view (the remainder of files) which can be started by loading the Index.html file into a web browser.
The intention of this documentation is to provide the API technical details of the each of the services, their parameters and the details of those parameters (e.g. which fields are required, maximum lengths allowed, etc.)
Important Note:
Since this documentation is produced directly from source code it is the most accurate view of the current state of the PASI core but may not reflect the end state in early releases. To have a clear understanding of the end state of a service the business documentation should be used along side the technical documentation. As code becomes "production ready" the documentation will align with the business documentation.
The format of the documentation will be familiar to developers that regularly work on the Microsoft .NET platform. The style is similar to that found on https://msdn.microsoft.com. For Java developers the closest comparison would be the documentation produced by Javadoc (https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/).
We recommend you start by reading some of the higher level information about the PASI core before focusing on the API (sections like Authentication & Authorization, Update PASI Core Data, Data Synchronization, etc).
Endpoints
PASI Core is implemented as a web service. The web service is published on an endpoint identified by a URL location. As of 2012 PASI Core implements a versioning scheme to facilitate updates to existing service operations that may not be backwards compatible from a web service definition (WSDL) or API perspective. Before 2012 PASI Core was published on a single endpoint. This endpoint was produced before PASI Core adopted a versioning strategy. The "version" of this endpoint is considered to be "2009" and was referenced as follows:
(host-info)/PASIService.svc
The data contracts for this endpoint are defined under PASI.DataContract.V2009. Moving forward all new endpoints for the PASI Core web service will have a version consisting of a year and a month and will be referenced as follows:
(host-info)/(yyyy)/(mm)/PASIService.svc
The version of the latest PASI Core endpoint is 2012/04. The service contract for this endpoint is defined under IPASIService201204. The data contracts specific to this endpoint are defined under PASI.DataContract.V201204. The new 2012/04 endpoint also uses data contracts from the 2009 endpoint. The version of the data contracts for a particular end point will always be less than or equal to the version of the endpoint itself. The PASI.DataContract section contains data contracts that have no version associated with them and do not adhere to the versioning strategy.
In general the latest version of the endpoint for PASI Core should be consumed. The previous endpoint should be consulted only if the service method being sought no longer exists in the latest endpoint. The intention is that old endpoint will eventually be discontinued so that PASI Core only implements one endpoint and never more than two endpoints (the current and previous) at any time.
Services Operations
To view details about the services operations that the PASI core offers select the PASI.ServiceContract namespace. By expanding this section the methods are then exposed. Selecting a method will provide more details about the selected method.
From the service operation screen you can find details of what the service is for, details the method signature and any validation errors that may be returned. A class diagram is available to provide an understanding of how the objects are related for both the request and response. There is also a field by field breakdown of the properties within the request and response that explain the data type, if the field is required, and any other important information about the field (e.g. maximum length, accepted values, etc.).
This shows the method signature for HelloWorld. It is expecting a HelloWorldRequest and returns a String
Each of the validation rules can be clicked on to find out the details of what the rule is and how it is implemented.
Each service will display the details of the request and response. This provides quick access to information like: Is the field required, maximum string length, a list of accepted values, etc.
Each service will display a class diagram of the request and response.
